PD Collection CD 1/PD Collection CD 1.iso/programer2/aoflib/!ReadMe

Text File | 1996-05-28 | 5.4 KB | 187 lines

AOFLib by William Gibbons of DWS
------
AOFLib is a small BASIC library designed to let you save ARM code created
with the BASIC assembler as AOF files. This allows them to be incorportated
into programs written in C and other high-level languages.

See the Example directory for an example of linking BASIC assembler with a C
program.


Using AOFLib
------------
AOFLib must be included in your BASIC source program via the LIBRARY command.
If you don't want to do this every in every BASIC source you can use INSTALL
to install the library.

You must call PROCInit before you use AOFLib; this initialises AOFLib

AOFLib provides ways of exporting labels from BASIC assembler and importing
labels into assembler.

To export an address, you can use:
FNexp("<Label name>") from your BASIC source.

You must assemble your code in this way:
DIM code% &2000
FOR pass%=4 TO 6 STEP 2
 O%=code%:P%=0
 [opt pass%
  ...
  FNexp("bloggs")
  ...
  your code here
  ...
 ]
NEXT

ie, you must use pass% as your assembly counter. If you normally use
something else, you can replace all instances of pass% in AOFLib with
whatever you normally use using Edit's Search + Replace facility.

It isn't important that you use the name "code%", but it is important that
pass% goes from 4 to 6, and that P% is set to 0. If it isn't, label
address will be wrong.

That example will export the label name "bloggs" which can now be called as
a procedure name from C source (see below).

You can export up to 64 label names in one BASIC assembler source file.

To import label names, there are two procedures: FNimp("<Label name>" and
FNima("<Label name>").

Use FNimp() after B[L] and ADR

Eg:
   ADR R0,str
   BL FNimp("printf")

will pass the string pointed to by str to the function printf(), and:

   ADR R0,FNimp("printf")

will put the address of the printf() function in the register R0.


Use FNima() when you want to put the address of a label in a word, eg

   EQUD FNima("printf")

will put the address of the function printf() into memory.


Additionally, PROCexp("<Label name>",<Value>) is provided to let you export
a label.
Use:
PROCexp("bloggs",a%)
to export the (area-relative) value a% as a label with name "bloggs".


Then use PROCSave to save your assembler procedure as an AOF file, eg:
PROCSave("ADFS::4.$.AOFFile",code%,O%)
will save the ARM code between the addresses code% and O% to the file
ADFS::4.$.AOFFile and will save any labels you exported or imported too.

The AOF file can now be linked with C programs (see below)

Linking AOF files with C programs
---------------------------------
AOF files to be linked with C programs must be saved in the "o" directory
of your C program source.

Any routines you write with the BASIC assembler will be unknown to C.
They have to be prototyped so that your C compiler recognises them and
doesn't give an error when you use them.

An example:
int foo(char k);

defines the foo() function as taking a character in R0 and returning an
integer in R0.

You can then call the function from your C program, like so:
  int a;
  a = foo('f');

Assembler routines must obey the APCS if they are to be successfully
interworked with C.

When you compile your program, it won't be linked to your assembler AOF
files, so you have to tell the compiler to do this explicitly.

If you're using EasyC, you can drag AOF files onto the Object part of the
EasyC window, and then compile + link in the normal way.

If you're using Acorn's C, you have to either use make files or an Obey file,
or add the AOF filenames to the list of libraries in !CC.

An example of using Obey files:
  *CC c.program -IC: -throwback -LC:o.stubs,o.eg -Desktop ^ -o output

will compile "c.program" and link it to the AOF file "o.eg"

See the Example directory for an example of this.


History
-------
0.01    First working version. No support for importing.
0.02    String table is now zero-padded to stop DecAOF thinking there is an
          extra symbol at the end of the string table.
0.03    Support for importing PC-relative labels added
0.04    Support for importing Additive labels added.
0.05    Bug in memory allocation fixed.


Licence
-------
AOFLib is freeware, and remains (c) Dizzy Wizard Software at all times.

You may freely distribute this archive provided it is unaltered, and no
charge is made for it.

If you wish to put it on a disc in a PD library and you charge no more than
£2 per disc (inc. postage & packing) then feel free to do so.


Technical
---------
AOFLib creates AOF files of version 150 with type 1 relocations.

It creates read/write code areas.
If you want the source code for AOFLib, feel free to Email me at the address
below and I will send it to you.

In the future this library may be re-written as a module and include support
for multiple areas.


Credits
-------
AOFLib was created with Edit, and AOF files were debugged using Zap 1.30.

Thanks to James Larcombe for spotting the problem with DecAOF.

Greetings to: James Larcombe, John Wright, Frederic Elisei, Ben Ingram,
              Dave Williams, Alain Brobecker et al.


Contacting Dizzy Wizard Software
--------------------------------
My Email address is [e-mail]
My real address is:

  William Gibbons
  52 Hurst Park Avenue
  Cambridge
  England
  CB4 2AE


The Dizzy Wizard Software Email address is [e-mail]

Email us for a complete catalogue of our software, or mail us as user
"Dizzy Wizard Software" on Digital DataBank BBS (tel. [phone])